openapi: 3.0.1
tags:
  - name: customer
    description: counterparty api tag description
  - name: counterparty
    description: counterparty api tag description
info:
  title: Testing SD Jan 19
  description: Provides examples for a conformant API
  version: 1.0.1
paths:
  /{entity}/me:
    \$ref: ./paths/example.yaml
  /books/{id}:
    \$ref: ./paths/example.yaml
  /health:
    get:
      operationId: get-health
      summary: health check endpoint
      description: >-
        Health check endpoint for checking API. Provides information on if the
        service is up and running
      security:
        - OAuth2:
            - test-sd.readonly
            - test-sd.accessonly
            - test-sd.read-write-testonly
      parameters:
        - name: x-request-id
          in: header
          description: A unique ID for each API request.
          style: form
          explode: false
          schema:
            type: string
            format: uuid
            example: 582dd6b6-61d3-46d5-bcdc-81fad7c27822
            pattern: >-
              ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
            maxLength: 10
      responses:
        '200':
          description: successful operation
          content:
            application/health+json:
              schema:
                $ref: '#/components/schemas/health'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          description: Client error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
  /health/info:
    get:
      operationId: get-healthinfo
      summary: health check endpoint for downstream
      description: Health check endpoint for checking API downstream services
      parameters:
        - name: x-request-id
          in: header
          description: A unique ID for each API request.
          style: form
          explode: false
          schema:
            type: string
            format: uuid
            example: 582dd6b6-61d3-46d5-bcdc-81fad7c27822
            pattern: >-
              ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
            maxLength: 10
      responses:
        '200':
          description: sucessful operation
          content:
            application/health+json:
              schema:
                $ref: '#/components/schemas/healthInfo'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          description: Client error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
  /party-reference/customers:
    description: This returns the list of customers.
    get:
      tags:
        - customer
      description: Provides the reference data of the Customers
      summary: Provides the reference data of Customers
      operationId: get-customers
      externalDocs:
        description: Description of documentation link
        url: https://api.standards.cba/rest_getting_started/
      security:
        - OAuth2:
            - test-sd.readonly
      parameters:
        - name: x-request-id
          in: header
          description: A unique ID for each API request.
          style: form
          explode: false
          schema:
            type: string
            format: uuid
            example: 582dd6b6-61d3-46d5-bcdc-81fad7c27822
            pattern: >-
              ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
            maxLength: 10
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/x-idempotency-id'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerDataSet'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          description: Client error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '401':
          description: Unauthorised access error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '403':
          description: >-
            The request contained valid data and was understood by the server,
            but the server is refusing action
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
            Retry-After:
              description: >-
                Indicates how long the client should wait before making a
                follow-up request.
              schema:
                type: string
                minLength: 2
                maxLength: 3
                format: uuid
                pattern: >-
                  ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
              examples:
                delay-seconds:
                  value: '120'
        '500':
          description: Server error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
  /party-reference/customers/{customer-id}:
    get:
      tags:
        - customer
      summary: Retrieves customer
      operationId: get-customer
      description: Retrieves requested customer data by a unique customer identifier.
      security:
        - OAuth2:
            - test-sd.writeonly
      parameters:
        - name: customer-id
          in: path
          required: true
          description: >-
            The unique identifier of the customer of which details are being
            accessed.
          schema:
            type: string
            minLength: 6
        - name: x-request-id
          in: header
          description: A unique ID for each API request.
          style: form
          explode: false
          schema:
            type: string
            format: uuid
            example: 582dd6b6-61d3-46d5-bcdc-81fad7c27822
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/x-idempotency-id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerModel'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '404':
          description: The requested customer was not found.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
    put:
      tags:
        - customer
      summary: Updates customer
      operationId: update-customer
      description: Updates the reference data of a customer.
      security:
        - OAuth2:
            - test-sd.testonly
            - test-sd.readonly
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customerDataSet'
      parameters:
        - name: customer-id
          in: path
          required: true
          description: >-
            The unique identifier of the customer of which details are being
            accessed.
          schema:
            type: string
            minLength: 6
        - name: name
          in: query
          style: form
          explode: false
          description: Name of the customer that needs to be updated
          schema:
            type: string
        - name: x-request-id
          in: header
          description: A unique ID for each API request.
          style: form
          explode: false
          schema:
            type: string
            format: uuid
            example: 582dd6b6-61d3-46d5-bcdc-81fad7c27822
        - $ref: '#/components/parameters/x-idempotency-id'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerDataSet'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          description: Client error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '401':
          description: Unauthorised access error response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
components:
  schemas:
    customerModel:
      type: object
      properties:
        id:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
        name:
          type: string
          pattern: ^[ A-Za-z0-9_,\"@.\/#&+-]*$
          maxLength: 1024
          example: ABC Corp Ltd
        dateOfBirth:
          type: string
          format: date
          description: birthday of the person format YYYY-MM-DD
          example: '1990-06-12'
        createdAt:
          type: string
          format: date-time
          description: date and time of the creation of the customer model
          example: '2023-06-25T06:43:40.252Z'
        modifiedAt:
          type: string
          format: date-time
          description: last date and time the customer model was modified
          example: '2023-06-29T06:43:40.252Z'
    customerDataSet:
      type: array
      items:
        $ref: '#/components/schemas/customerModel'
    error:
      title: Error
      type: object
      properties:
        code:
          type: string
          pattern: ^[A-Z]+(?:-[A-Z]+)*$
          minLength: 6
          maxLength: 36
          description: Error Code
          example: API-ERR
        message:
          type: string
          pattern: ^[ A-Za-z0-9_,\"@.\/#&+-]*$
          maxLength: 1024
          description: Description of Error
          example: Unable to retrieve customer list
        details:
          type: array
          minLength: 4
          maxLength: 36
          maxItems: 16
          description: customised schema with further details of the Error
          items:
            $ref: '#/components/schemas/errorDetail'
    errorDetail:
      title: ErrorDetail
      type: object
      properties:
        code:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
        message:
          type: string
          pattern: ^[ A-Za-z0-9_,\"@.\/#&+-]*$
          maxLength: 1024
      required:
        - code
    health:
      type: object
      properties:
        status:
          type: string
          description: Indicates whether service is acceptable or not
          enum:
            - HEALTHY
            - UNHEALTHY
            - DEGRADED
            - WARN
          example: HEALTHY
        message:
          type: string
          pattern: ^[ A-Za-z0-9_,\"@.\/#&+-]*$
          maxLength: 1024
        checks:
          type: object
          items:
            $ref: '#/components/schemas/checks'
      required:
        - status
    healthInfo:
      type: object
      properties:
        status:
          type: string
          description: Indicates whehter service is acceptable or not
          enum:
            - HEALTHY
            - UNHEALTHY
            - DEGRADED
            - WARN
          example: HEALTHY
        message:
          type: string
          pattern: ^[ A-Za-z0-9_,\"@.\/#&+-]*$
          maxLength: 1024
        checks:
          type: object
          items:
            $ref: '#/components/schemas/checks'
      required:
        - status
    checks:
      type: object
      description: >-
        provides detailed health statuses of additional downstrema systems and
        endpoints
      properties:
        name:
          type: string
          pattern: ^[A-Z]+(?:-[A-Z]+)*$
          minLength: 6
          maxLength: 36
          description: component name
        status:
          type: string
          description: indicates whether service status is acceptable or not
        message:
          type: array
          description: list of information
          items:
            type: string
            pattern: ^[A-Z]+(?:-[A-Z]+)*$
            maxLength: 1024
        affectedEndpoints:
          type: array
          maxLength: 36
          maxItems: 16
          description: endpoints affected by check
          items:
            type: string
            maxLength: 50
            example: /party-reference/customers
      required:
        - name
  headers:
    X-RateLimit-Limit:
      description: The maximum number of requests you're permitted to make per hour.
      required: false
      schema:
        type: number
        format: int32
        example: 10000
    X-RateLimit-Remaining:
      description: The number of requests remaining in the current rate limit window.
      required: false
      schema:
        type: number
        format: int32
        example: 9999
    X-RateLimit-Reset:
      description: >-
        The time at which the current rate limit window resets in UTC epoch
        seconds.
      required: false
      schema:
        type: number
        format: int32
        example: 1670798639
    Content-Language:
      description: Specifies the language of the content.
      required: false
      schema:
        type: string
        default: en-US
        example: de-DE
    Content-Type:
      description: >-
        Specifies the media type of the request or response body. If the content
        is a text-based type, the Content-type must include a character-set
        parameter of UTF-8.
      required: true
      schema:
        type: string
        example: application/json; charset=utf-8
  parameters:
    x-idempotency-id:
      name: x-idempotency-id
      in: header
      description: >-
        A unique id generated by consumer which the server uses to recognise
        subequent retries of the same request.
      style: form
      explode: false
      schema:
        type: string
        format: uuid
        example: b8b5ee3a-a755-45e5-a814-d869e432d9a9
    pageSize:
      name: pageSize
      in: query
      description: Maximum number of results to return at one time
      style: form
      explode: false
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 10
        example: 50
    page:
      name: page
      in: query
      description: The page of the results
      style: form
      explode: false
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 1
        example: 1
  securitySchemes:
    OAuth2:
      type: http
      scheme: basic
      description: These JWTs use RFC8725.
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            test-sd.testingonly: Read only access to API
            test-sd.readonly: Read write access to API
            test-sd.accessonly: Read write access to API
            test-sd.read-write-testonly: Read write access to API
